ATOM Documentation

← Back to App

SDLC Agents - AI-Powered Software Development

Overview

SDLC Agents are specialized AI agents designed to assist with Software Development Lifecycle tasks. These agents can analyze requirements, write code, create tests, review code, and manage deployments, all while operating under strict governance and safety controls.

**Key Benefits:**

  • Accelerated development cycles through AI-assisted coding
  • Consistent code quality through automated reviews
  • Comprehensive test coverage via intelligent test generation
  • Safe deployments with approval workflows
  • Full audit trail for compliance and debugging

**Safety Features:**

  • Tenant opt-in model (disabled by default)
  • Maturity-based permissions (student → intern → supervised → autonomous)
  • Per-agent-type enablement controls
  • Approval requirements for high-risk actions
  • Sandboxed code execution for untrusted operations
  • Comprehensive audit logging

**Use Cases:**

  • Automated code refactoring and modernization
  • Test suite generation and maintenance
  • Code review and security scanning
  • Deployment pipeline automation
  • Requirements analysis and project planning

---

Setup Guide

Prerequisites

Before enabling SDLC agents, ensure:

  • You have admin or super_admin role for your tenant
  • Your agents have reached appropriate maturity levels (see Agent Types below)
  • You understand the approval workflow requirements

Enabling SDLC Agents for Your Tenant

SDLC agents are **opt-in** and disabled by default for all tenants. To enable:

Step 1: Enable SDLC Master Switch

POST /api/sdlc/enable
Headers: Authorization: Bearer <admin-token>

**Response:**

{
  "success": true,
  "message": "SDLC agents enabled for tenant",
  "enabled": true
}

Step 2: Configure Agent Types

After enabling the master switch, configure which agent types to use:

// Enable specific agent types
await fetch('/api/sdlc/settings', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    enabled_agent_types: ['planner', 'reviewer', 'tester'],
    approval_required_for: ['deploy', 'write_code']
  })
})

Step 3: Verify Configuration

GET /api/sdlc/settings

**Response:**

{
  "sdlc_agents_enabled": true,
  "enabled_agent_types": {
    "planner": { "enabled": true, "config": {} },
    "reviewer": { "enabled": true, "config": {} },
    "tester": { "enabled": true, "config": {} }
  },
  "approval_required_for": ["deploy", "write_code"]
}

Agent Type Configuration

Each agent type has specific requirements and use cases:

Planner Agent Setup

  • **Maturity Required:** Intern or higher
  • **Safety Level:** SAFE
  • **Approval Required:** No (read-only operations)
  • **Best For:** Requirements analysis, project planning, effort estimation
const factory = new SDLCAgentFactory(db)
const planner = await factory.createAgent('planner', 'tenant-123', {
  project_name: 'E-commerce Platform',
  requirements: ['User authentication', 'Payment processing']
})

Coder Agent Setup

  • **Maturity Required:** Supervised or higher
  • **Safety Level:** MEDIUM_RISK
  • **Approval Required:** Yes (code modification)
  • **Best For:** Writing code, refactoring, adding documentation
  • **Sandbox:** Required (Docker isolation)
const coder = await factory.createAgent('coder', 'tenant-123', {
  project_id: 'project-456',
  repository_url: 'https://github.com/org/repo',
  coding_standards: 'PEP8 for Python, Prettier for TypeScript'
})

Tester Agent Setup

  • **Maturity Required:** Supervised or higher
  • **Safety Level:** LOW_RISK
  • **Approval Required:** No (test operations are safe)
  • **Best For:** Writing tests, generating mock data, coverage analysis
  • **Sandbox:** Required (test execution)
const tester = await factory.createAgent('tester', 'tenant-123', {
  target_coverage: 80,
  test_framework: 'pytest',
  mock_data_strategy: 'realistic'
})

Reviewer Agent Setup

  • **Maturity Required:** Intern or higher
  • **Safety Level:** SAFE
  • **Approval Required:** No (read-only analysis)
  • **Best For:** Code review, security scanning, style validation
const reviewer = await factory.createAgent('reviewer', 'tenant-123', {
  review_standards: 'Google Style Guide',
  security_checks: ['OWASP Top 10', 'SQL Injection'],
  style_rules: ['max-line-length', 'naming-conventions']
})

Deployer Agent Setup

  • **Maturity Required:** Autonomous only
  • **Safety Level:** HIGH_RISK
  • **Approval Required:** Yes (deployment is critical)
  • **Best For:** Deployment management, rollback operations
  • **Restrictions:** Only autonomous agents can deploy
const deployer = await factory.createAgent('deployer', 'tenant-123', {
  deployment_targets: ['staging', 'production'],
  approval_workflow: 'manual',
  rollback_on_failure: true
})

---

Architecture

System Components

┌─────────────────────────────────────────────────────────────┐
│                     Tenant Application                       │
│                  (User Interface & Settings)                 │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                   API Gateway (Next.js)                      │
│    /api/sdlc/settings  /api/sdlc/enable  /api/sdlc/agent-types│
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              SDLC Governance Layer (TypeScript)              │
│  ┌──────────────────┐  ┌──────────────────┐  ┌─────────────┐ │
│  │ Agent Types      │  │ Factory          │  │ Governance  │ │
│  │ Registry         │  │ Pattern          │  │ Service     │ │
│  └──────────────────┘  └──────────────────┘  └─────────────┘ │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│           Backend Service Layer (Python FastAPI)             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌─────────────┐ │
│  │ SDLC Agent       │  │ Episode          │  │ Project     │ │
│  │ Service          │  │ Service          │  │ Management  │ │
│  └──────────────────┘  └──────────────────┘  └─────────────┘ │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    Data Layer (PostgreSQL)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Agent Configs│  │ Audit Logs   │  │ SDLC Projects    │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Agent Type Registry

The agent type registry defines all available SDLC agents with their capabilities, maturity requirements, and safety constraints.

**Registry Structure:**

interface SDLCAgentType {
  id: 'planner' | 'coder' | 'tester' | 'reviewer' | 'deployer'
  name: string
  description: string
  capabilities: string[]           // Actions the agent can perform
  required_maturity: MaturityLevel // Minimum maturity level
  safety_level: SafetyLevel        // Risk assessment
  requires_approval: boolean       // Default approval requirement
  sandbox_required: boolean        // Docker isolation needed
}

**Capability Mappings:**

  • **Level 2 (INTERN+):** analyze_requirements, create_wbs, review_code, check_security
  • **Level 3 (SUPERVISED+):** write_code, refactor, write_tests, execute_tests
  • **Level 4 (AUTONOMOUS only):** deploy, rollback, delete_code, execute_shell

Tenant Opt-In System

SDLC agents use a multi-layer opt-in system:

  1. **Master Switch (sdlc_agents_enabled)**: Tenant-level enablement flag
  2. **Per-Agent-Type Enablement**: Fine-grained control over each agent type
  3. **Approval Requirements**: Configure which actions require manual approval

**Settings Storage:**

CREATE TABLE sdlc_agent_configs (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  agent_type VARCHAR(50) NOT NULL,
  enabled BOOLEAN DEFAULT false,
  config JSONB DEFAULT '{}',
  UNIQUE(tenant_id, agent_type)
);

Governance Integration

SDLC agents integrate with the existing AgentGovernanceService:

**Maturity-Based Permissions:**

STUDENT   → Can only use planner/reviewer (read-only)
INTERN    → + Can use planner/reviewer safely
SUPERVISED→ + Can use coder/tester with approval
AUTONOMOUS → + Can use deployer with approval

**Action Complexity Levels:**

const ACTION_COMPLEXITY = {
  // Level 1: Read-only (student+)
  "search": 1, "read": 1, "analyze": 1,

  // Level 2: Analysis (intern+)
  "analyze_requirements": 2, "review_code": 2,

  // Level 3: State change (supervised+)
  "write_code": 3, "create": 3, "update": 3,

  // Level 4: Critical (autonomous only)
  "deploy": 4, "delete": 4, "execute_shell": 4
}

Database Schema

**sdlc_agent_configs:**

Per-tenant, per-agent-type configuration with enablement flags and custom settings.

**sdlc_audit_log:**

Complete audit trail of all SDLC agent actions with approval information and episode linkage.

**sdlc_projects:**

Project tracking with repository URLs and status management.

**Row-Level Security:**

All tables use PostgreSQL RLS for tenant isolation:

ALTER TABLE sdlc_audit_log ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON sdlc_audit_log
  USING (tenant_id = current_setting('app.current_tenant_id')::UUID);

---

API Reference

Frontend API Routes (Next.js)

GET /api/sdlc/settings

Retrieve tenant SDLC settings.

**Response:**

{
  "sdlc_agents_enabled": boolean,
  "enabled_agent_types": {
    "planner": { "enabled": boolean, "config": object },
    "coder": { "enabled": boolean, "config": object }
  },
  "approval_required_for": string[]
}

PUT /api/sdlc/settings

Update tenant SDLC settings (admin only).

**Request:**

{
  "enabled_agent_types?: string[],
  "approval_required_for?: string[]
}

POST /api/sdlc/enable

Enable SDLC agents for tenant (admin only).

GET /api/sdlc/agent-types

List all available SDLC agent types with capabilities.

**Response:**

[
  {
    "id": "planner",
    "name": "Planning Agent",
    "description": "...",
    "capabilities": ["analyze_requirements", "create_wbs"],
    "required_maturity": "intern",
    "safety_level": "SAFE",
    "enabled": true
  }
]

Backend Service Methods

SDLCAgentService.get_tenant_sdlc_settings(tenant_id)

Retrieve tenant SDLC configuration.

SDLCAgentService.is_agent_type_enabled(tenant_id, agent_type)

Check if specific agent type is enabled.

SDLCAgentService.log_sdlc_action(...)

Log SDLC action to audit trail.

SDLCAgentService.create_sdlc_episode(...)

Create episode with SDLC metadata.

SDLCAgentService.get_sdlc_projects(tenant_id, status?)

Retrieve tenant SDLC projects.

SDLCAgentService.create_sdlc_project(...)

Create new SDLC project.

---

Agent Types

Planner Agent

**Capabilities:**

  • analyze_requirements - Analyze and document requirements
  • create_wbs - Create work breakdown structures
  • map_dependencies - Map task dependencies
  • estimate_effort - Estimate development effort

**Maturity:** Intern+

**Safety:** SAFE

**Approval:** Not required

**Use Cases:**

  • Requirements gathering and documentation
  • Project planning and milestone creation
  • Dependency mapping and critical path analysis
  • Effort estimation for sprint planning

---

Coder Agent

**Capabilities:**

  • write_code - Write new code from specifications
  • refactor - Refactor existing code
  • add_tests - Add unit tests for new code
  • document_code - Generate code documentation

**Maturity:** Supervised+

**Safety:** MEDIUM_RISK

**Approval:** Required

**Sandbox:** Required (Docker isolation)

**Use Cases:**

  • Feature implementation from specs
  • Code modernization and refactoring
  • Test generation for existing code
  • Documentation generation

---

Tester Agent

**Capabilities:**

  • write_tests - Write test cases
  • execute_tests - Run test suites
  • generate_mock_data - Generate test data
  • analyze_coverage - Analyze test coverage

**Maturity:** Supervised+

**Safety:** LOW_RISK

**Approval:** Not required

**Sandbox:** Required (test isolation)

**Use Cases:**

  • Automated test generation
  • Test suite maintenance
  • Coverage analysis and improvement
  • Mock data generation for testing

---

Reviewer Agent

**Capabilities:**

  • review_code - Review code for quality issues
  • check_security - Scan for security vulnerabilities
  • validate_style - Validate coding style
  • suggest_improvements - Suggest code improvements

**Maturity:** Intern+

**Safety:** SAFE

**Approval:** Not required

**Use Cases:**

  • Pull request code review
  • Security vulnerability scanning
  • Style guide compliance checking
  • Best practices recommendations

---

Deployer Agent

**Capabilities:**

  • deploy - Deploy code to environments
  • rollback - Rollback failed deployments
  • monitor_deployment - Monitor deployment health
  • manage_environments - Manage deployment environments

**Maturity:** Autonomous only

**Safety:** HIGH_RISK

**Approval:** Required

**Use Cases:**

  • Automated deployment pipelines
  • Rollback on failure detection
  • Production environment management
  • Deployment monitoring and alerting

---

Safety & Security

Sandboxed Execution

Code execution happens in isolated Docker containers:

**Container Restrictions:**

  • CPU limits (1 core max)
  • Memory limits (1GB max)
  • Network restrictions (no external access without approval)
  • Filesystem isolation (temporary workspace only)
  • Timeout enforcement (30 minutes max execution)

**Sandbox Configuration:**

container_config = {
    "image": "python:3.11-slim",
    "cpu_limit": 1.0,
    "memory_limit": "1g",
    "network_mode": "none",
    "read_only": True,
    "timeout": 1800  # 30 minutes
}

Approval Workflow

High-risk actions require manual approval:

**Approval Process:**

  1. Agent requests approval for action
  2. Request queued in approval queue
  3. Admin notified via email/UI
  4. Admin reviews and approves/rejects
  5. Agent executes or cancels based on decision

**Approval Expiration:** 24 hours (requests older than 24h auto-reject)

**Audit Trail:**

{
  "action": "deploy",
  "agent_id": "agent-deployer",
  "approval_required": true,
  "approved_by": "admin-123",
  "approved_at": "2026-02-20T18:00:00Z",
  "approval_expires": "2026-02-21T18:00:00Z"
}

Maturity Level Enforcement

**STUDENT (Read-Only):**

  • Can use: planner (analyze), reviewer (review)
  • Cannot: Write code, execute tests, deploy

**INTERN (Low-Risk Operations):**

  • Can use: planner, reviewer (all capabilities)
  • Cannot: Write code, execute tests, deploy

**SUPERVISED (Medium-Risk with Approval):**

  • Can use: planner, reviewer, tester (all), coder (with approval)
  • Cannot: Deploy

**AUTONOMOUS (All Operations with Approval):**

  • Can use: All agent types
  • Deploy requires approval even for autonomous

Audit Logging

Every SDLC action is logged with complete context:

**Log Entry:**

{
  "id": "log-uuid",
  "tenant_id": "tenant-123",
  "agent_id": "agent-coder",
  "agent_type": "coder",
  "action": "write_code",
  "input_summary": "Implement user authentication",
  "outcome": "Code written successfully",
  "success": true,
  "approval_required": true,
  "approved_by": "admin-123",
  "constitutional_violations": [],
  "episode_id": "episode-456",
  "created_at": "2026-02-20T18:00:00Z"
}

**Query Audit Logs:**

logs = sdlc_service.get_sdlc_audit_logs(
    tenant_id="tenant-123",
    agent_id="agent-coder",
    agent_type="coder",
    limit=100
)

Tenant Isolation

**Row-Level Security (RLS):**

All database queries filter by tenant_id using PostgreSQL RLS policies.

**Per-Tenant Configuration:**

Each tenant has isolated agent type configurations and settings.

**Sandboxed Filesystems:**

Code execution uses per-tenant, per-execution temporary directories.

**Rate Limiting:**

SDLC operations count against tenant rate limits (abuse protection).

---

Usage Examples

Enabling SDLC Agents

// Enable SDLC for tenant
await fetch('/api/sdlc/enable', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`
  }
})

// Configure agent types
await fetch('/api/sdlc/settings', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${adminToken}`
  },
  body: JSON.stringify({
    enabled_agent_types: ['planner', 'coder', 'tester'],
    approval_required_for: ['deploy', 'write_code']
  })
})

Creating Planning Agent

import { SDLCAgentFactory } from '@/lib/ai/sdlc-agent-factory'

const factory = new SDLCAgentFactory(db)
const planner = await factory.createAgent('planner', 'tenant-123', {
  project_name: 'E-commerce Platform',
  requirements: [
    'User registration and authentication',
    'Product catalog with search',
    'Shopping cart and checkout',
    'Payment integration'
  ]
})

// Analyze requirements
const analysis = await planner.execute('analyze_requirements', {
  requirements: requirements_text
})

console.log(analysis.wbs)      // Work breakdown structure
console.log(analysis.effort)    // Effort estimates
console.log(analysis.dependencies) // Task dependencies

Checking Permissions

import { SDLCAgentGovernanceService } from '@/lib/ai/sdlc-governance'

const governance = new SDLCAgentGovernanceService(db)

// Check if agent can perform action
const decision = await governance.canPerformSDLCAction(
  'tenant-123',
  'agent-intern',
  'planner',
  'analyze_requirements'
)

if (decision.allowed) {
  console.log('Action allowed, approval required:', decision.requires_approval)
} else {
  console.log('Action blocked:', decision.reason)
}

Code Generation with Approval

const coder = await factory.createAgent('coder', 'tenant-123', {
  project_id: 'project-456',
  repository_url: 'https://github.com/org/repo'
})

// Request code generation (requires approval)
const result = await governance.canPerformSDLCAction(
  'tenant-123',
  'agent-coder',
  'coder',
  'write_code'
)

if (result.allowed && result.requires_approval) {
  // Submit approval request
  await fetch('/api/approvals/request', {
    method: 'POST',
    body: JSON.stringify({
      agent_id: 'agent-coder',
      action: 'write_code',
      input_summary: 'Implement user authentication flow'
    })
  })

  // Wait for approval (poll or use webhook)
  // ... admin approves ...

  // Execute action
  const code = await coder.execute('write_code', {
    specification: 'Implement JWT authentication with refresh tokens',
    language: 'python',
    framework: 'FastAPI'
  })
}

Automated Testing

const tester = await factory.createAgent('tester', 'tenant-123', {
  target_coverage: 80,
  test_framework: 'pytest'
})

// Generate tests
const tests = await tester.execute('write_tests', {
  source_file: 'app/auth.py',
  coverage_target: 80
})

// Execute tests
const results = await tester.execute('execute_tests', {
  test_files: ['tests/test_auth.py'],
  environment: 'staging'
})

console.log('Coverage:', results.coverage_percentage)
console.log('Passed:', results.passed_count)
console.log('Failed:', results.failed_count)

Code Review

const reviewer = await factory.createAgent('reviewer', 'tenant-123', {
  review_standards: 'PEP8',
  security_checks: ['OWASP Top 10']
})

// Review pull request
const review = await reviewer.execute('review_code', {
  pull_request_id: 123,
  repository_url: 'https://github.com/org/repo'
})

console.log('Issues found:', review.issues.length)
console.log('Security issues:', review.security_issues)
console.log('Style violations:', review.style_violations)

---

Troubleshooting

SDLC Agents Not Appearing in Settings

**Symptoms:** Settings page shows "SDLC agents disabled" with no option to enable.

**Solutions:**

  1. Verify you have admin or super_admin role
  2. Check /api/sdlc/settings returns valid response
  3. Enable master switch with POST /api/sdlc/enable
  4. Refresh settings page

Agent Type Enablement Not Working

**Symptoms:** Agent type shows as disabled after enabling.

**Solutions:**

  1. Check sdlc_agent_configs table for entry:
  2. Verify enabled column is true
  3. Clear governance cache: SDLCAgentGovernanceService.clearCache()
  4. Check for database RLS policy issues

Approval Workflow Not Triggering

**Symptoms:** High-risk actions execute without approval.

**Solutions:**

  1. Verify agent type has requires_approval: true
  2. Check action is in HIGH_RISK_ACTIONS list
  3. Confirm governance check is called before execution
  4. Review audit logs for approval_required flag

Audit Logs Not Appearing

**Symptoms:** No entries in sdlc_audit_log table.

**Solutions:**

  1. Check database connection and table exists:
  2. Verify RLS policies allow inserts
  3. Check application logs for insert errors
  4. Confirm log_sdlc_action() is called

Permission Errors

**Symptoms:** "Access denied" or "Insufficient permissions" errors.

**Solutions:**

  1. Verify agent maturity level meets requirement
  2. Check agent type is enabled for tenant
  3. Confirm user has admin role for settings changes
  4. Review governance cache (may be stale)

---

Best Practices

1. Start with Safe Agents

Enable planner and reviewer agents first (read-only, safe operations):

enabled_agent_types: ['planner', 'reviewer']

2. Enable Coder/Tester Only for Trusted Users

These agents modify code and require higher maturity:

enabled_agent_types: ['planner', 'reviewer', 'tester']
// Add 'coder' only when trust established

3. Keep Deployer Disabled Until Proven

Deployer agent should be the last to enable:

  • Only autonomous agents can deploy
  • Requires thorough testing in staging first
  • Should have rollback procedures in place

4. Require Approval for Write Operations

Conservative approval settings:

approval_required_for: [
  'deploy',
  'write_code',
  'delete_code',
  'execute_shell'
]

5. Review Audit Logs Regularly

Check audit logs weekly for:

  • Unusual activity patterns
  • Failed actions with constitutional violations
  • Approval rejection patterns
  • Agent performance metrics

6. Test in Non-Production First

Always test SDLC agents in staging:

  • Verify code generation quality
  • Test approval workflow end-to-end
  • Validate sandbox isolation
  • Check rollback procedures

7. Monitor Agent Maturity Progression

Track agent readiness for higher maturity levels:

  • Review graduation exam results
  • Check zero-intervention ratios
  • Monitor constitutional compliance scores

8. Set Realistic Effort Estimates

Start with conservative estimates:

  • Planner agents tend to underestimate
  • Add 20-30% buffer to estimates
  • Track actual vs. estimated for calibration

---

Limitations

Execution Constraints

  • **Sandboxed Code Execution:** No direct system access
  • **Timeout Limits:** 30 minutes max per operation
  • **Memory Limits:** 1GB max per container
  • **Network Restrictions:** No external network access (without approval)

Deployment Constraints

  • **Whitelisted Targets Only:** Deployment environments must be pre-approved
  • **Rollback Required:** Failed deployments must auto-rollback
  • **Manual Approval:** All deployments require human approval
  • **Audit Trail:** Complete deployment history logged

Agent Limitations

  • **STUDENT Agents:** Cannot write code or deploy (read-only)
  • **INTERN Agents:** Limited to read and low-risk operations
  • **SUPERVISED Agents:** Need approval for write operations
  • **AUTONOMOUS Agents:** Still need approval for deployments

Rate Limiting

  • **Daily Execution Limits:** Based on tenant plan tier
  • **Concurrent Operations:** Limited by tenant configuration
  • **Resource Quotas:** CPU, memory, and storage caps apply

Data Access

  • **Tenant Isolation:** Agents can only access tenant's data
  • **No Cross-Tenant Operations:** Strict isolation enforced
  • **RLS Policies:** All database queries filtered by tenant_id

---

Related Documentation

  • **Agent Governance:** /docs/AGENT_GOVERNANCE.md - Maturity levels and permissions
  • **Episode Service:** /docs/EPISODE_SERVICE.md - Execution tracking and learning
  • **Graduation System:** /docs/GRADUATION_SYSTEM.md - Agent maturity progression
  • **Package Management:** /backend-saas/docs/PACKAGE_MANAGEMENT.md - Safe package installation

---

Support

For issues or questions:

  1. Check troubleshooting section above
  2. Review audit logs for error details
  3. Check agent maturity and enablement status
  4. Contact support with tenant ID and error details

**Version:** 1.0.0

**Last Updated:** 2026-02-20